<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
	<head>
		<title>Source Text</title>
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
		<meta name="viewport" content="width=device-width initial-scale=1">
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
		<meta http-equiv="Content-Language" content="en-gb">

<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
<script>
function togglePopup(material_id) {
  var popup = document.getElementById(material_id);
  popup.classList.toggle("show");
}
</script>

<link href="../docs-assets/Popups.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/ConsoleText-Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
		
	</head>
	<body class="commentary-font">
		<nav role="navigation">
		<h1><a href="../index.html"><img src="../docs-assets/Inform.png" height=72> </a></h1>
<ul><li><a href="../index.html">home</a></li>
</ul><h2>Compiler</h2><ul>
<li><a href="../structure.html">structure</a></li>
<li><a href="../inbuildn.html">inbuild</a></li>
<li><a href="../inform7n.html">inform7</a></li>
<li><a href="../intern.html">inter</a></li>
<li><a href="../services.html">services</a></li>
<li><a href="../secrets.html">secrets</a></li>
</ul><h2>Other Tools</h2><ul>
<li><a href="../inblorbn.html">inblorb</a></li>
<li><a href="../inform6.html">inform6</a></li>
<li><a href="../inpolicyn.html">inpolicy</a></li>
</ul><h2>Resources</h2><ul>
<li><a href="../extensions.html">extensions</a></li>
<li><a href="../kits.html">kits</a></li>
</ul><h2>Repository</h2><ul>
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=0> github</a></li>
</ul><h2>Related Projects</h2><ul>
<li><a href="https://github.com/ganelson/inweb"><img src="../docs-assets/github.png" height=0> inweb</a></li>
<li><a href="https://github.com/ganelson/intest"><img src="../docs-assets/github.png" height=0> intest</a></li>
</ul>
		</nav>
		<main role="main">
		<!-- Weave of 'Source Text' generated by inweb -->
<div class="breadcrumbs">
    <ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../inbuildn.html">Inbuild Modules</a></li><li><a href="index.html">supervisor</a></li><li><a href="index.html#6">Chapter 6: Inform Source Text</a></li><li><b>Source Text</b></li></ul></div>
<p class="purpose">Using the lexer and syntax analysis modules to read in Inform 7 source text.</p>

<ul class="toc"><li><a href="6-st.html#SP1">&#167;1. Bridge to the Lexer</a></li><li><a href="6-st.html#SP4">&#167;4. Bridge to the problems system</a></li><li><a href="6-st.html#SP6">&#167;6. Bridge to the syntax analyser</a></li></ul><hr class="tocbar">

<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;1. Bridge to the Lexer.</b>Lexing is the business of the <a href="../words-module/index.html" class="internal">words</a> module, and we need to tell it what
data type to use when referencing natural languages.
</p>

<pre class="definitions code-font"><span class="definition-keyword">define</span> <span class="constant-syntax">NATURAL_LANGUAGE_WORDS_TYPE</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">inform_language</span>
</pre>
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. </b>Lexical errors &mdash; overly long words, half-open quotations, and such &mdash; are
converted into copy errors and attached to the copy currently being worked on.
The following callback function performs that service.
</p>

<p class="commentary"><a href="../words-module/index.html" class="internal">words</a> has no convenient way to keep track of what copy we're working on,
so we will simply store it in a global variable.
</p>

<pre class="definitions code-font"><span class="definition-keyword">define</span> <span class="constant-syntax">PROBLEM_WORDS_CALLBACK</span><span class="plain-syntax"> </span><a href="6-st.html#SP2" class="function-link"><span class="function-syntax">SourceText::lexer_problem_handler</span></a>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> *</span><span class="identifier-syntax">currently_lexing_into</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">SourceText::lexer_problem_handler</span><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">err</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">desc</span><span class="plain-syntax">, </span><span class="identifier-syntax">inchar32_t</span><span class="plain-syntax"> *</span><span class="identifier-syntax">word</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">err</span><span class="plain-syntax"> == </span><span class="identifier-syntax">MEMORY_OUT_LEXERERROR</span><span class="plain-syntax">)</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">Errors::fatal</span><span class="plain-syntax">(</span><span class="string-syntax">"Out of memory: unable to create lexer workspace"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">currently_lexing_into</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">copy_error</span><span class="plain-syntax"> *</span><span class="identifier-syntax">CE</span><span class="plain-syntax"> = </span><a href="2-ce.html#SP2" class="function-link"><span class="function-syntax">CopyErrors::new_WT</span></a><span class="plain-syntax">(</span><span class="constant-syntax">LEXER_CE</span><span class="plain-syntax">, </span><span class="identifier-syntax">err</span><span class="plain-syntax">, </span><span class="identifier-syntax">word</span><span class="plain-syntax">, </span><span class="identifier-syntax">desc</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><a href="2-cps.html#SP5" class="function-link"><span class="function-syntax">Copies::attach_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">currently_lexing_into</span><span class="plain-syntax">, </span><span class="identifier-syntax">CE</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    }</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. </b>This next function is our bridge to the lexer (see <a href="../words-module/3-tff.html" class="internal">Text From Files (in words)</a>),
and is used for reading text files of source into either projects or extensions.
Note that it doesn't attach the fed text to the copy: the caller must do that,
perhaps combining our feed with that of others.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">source_reader_in_documentation_only_mode</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>

<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">SourceText::for_documentation_only</span><button class="popup" onclick="togglePopup('usagePopup1')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup1">Usage of <span class="code-font"><span class="function-syntax">SourceText::for_documentation_only</span></span>:<br/>Extension Services - <a href="5-es.html#SP14">&#167;14</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">state</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">old_state</span><span class="plain-syntax"> = </span><span class="identifier-syntax">source_reader_in_documentation_only_mode</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">source_reader_in_documentation_only_mode</span><span class="plain-syntax"> = </span><span class="identifier-syntax">state</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">old_state</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>

<span class="identifier-syntax">source_file</span><span class="plain-syntax"> *</span><span class="function-syntax">SourceText::read_file</span><button class="popup" onclick="togglePopup('usagePopup2')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup2">Usage of <span class="code-font"><span class="function-syntax">SourceText::read_file</span></span>:<br/>Extension Services - <a href="5-es.html#SP12">&#167;12</a><br/>Project Services - <a href="5-ps2.html#SP37_2">&#167;37.2</a><br/>Inclusions - <a href="6-inc.html#SP2_2">&#167;2.2</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax">, </span><span class="identifier-syntax">ls_web</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">synopsis</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">primary</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">documentation_only</span><span class="plain-syntax"> = </span><span class="identifier-syntax">source_reader_in_documentation_only_mode</span><span class="plain-syntax">;</span>

<span class="plain-syntax">    </span><span class="identifier-syntax">currently_lexing_into</span><span class="plain-syntax"> = </span><span class="identifier-syntax">C</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">general_pointer</span><span class="plain-syntax"> </span><span class="identifier-syntax">ref</span><span class="plain-syntax"> = </span><span class="identifier-syntax">STORE_POINTER_inbuild_copy</span><span class="plain-syntax">(</span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">leaf</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Filenames::get_leafname</span><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">primary</span><span class="plain-syntax">) </span><span class="identifier-syntax">leaf</span><span class="plain-syntax"> = </span><span class="identifier-syntax">I</span><span class="string-syntax">"main source text"</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">mode</span><span class="plain-syntax"> = </span><span class="identifier-syntax">UNICODE_UFBHM</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">target_vm</span><span class="plain-syntax"> *</span><span class="identifier-syntax">vm</span><span class="plain-syntax"> = </span><a href="1-ic.html#SP11" class="function-link"><span class="function-syntax">Supervisor::current_vm</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">TargetVMs::is_16_bit</span><span class="plain-syntax">(</span><span class="identifier-syntax">vm</span><span class="plain-syntax">)) </span><span class="identifier-syntax">mode</span><span class="plain-syntax"> = </span><span class="identifier-syntax">ZSCII_UFBHM</span><span class="plain-syntax">;</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">succeeded</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">source_file</span><span class="plain-syntax"> *</span><span class="identifier-syntax">sf</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">W</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">succeeded</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">WebStructure::read_web_source</span><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">, </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="named-paragraph-container code-font"><a href="6-st.html#SP3_1" class="named-paragraph-link"><span class="named-paragraph">Deal with literate source errors</span><span class="named-paragraph-number">3.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">succeeded</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">sf</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TextFromFiles::feed_open_file_into_lexer</span><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">,</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">leaf</span><span class="plain-syntax">, </span><span class="identifier-syntax">documentation_only</span><span class="plain-syntax">, </span><span class="identifier-syntax">ref</span><span class="plain-syntax">, </span><span class="identifier-syntax">mode</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        }</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">FILE</span><span class="plain-syntax"> *</span><span class="identifier-syntax">handle</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Filenames::fopen</span><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="string-syntax">"r"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">handle</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">sf</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TextFromFiles::feed_open_file_into_lexer</span><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="identifier-syntax">handle</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">,</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">leaf</span><span class="plain-syntax">, </span><span class="identifier-syntax">documentation_only</span><span class="plain-syntax">, </span><span class="identifier-syntax">ref</span><span class="plain-syntax">, </span><span class="identifier-syntax">mode</span><span class="plain-syntax">);</span>
<span class="plain-syntax">            </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sf</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">                </span><a href="2-cps.html#SP5" class="function-link"><span class="function-syntax">Copies::attach_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">, </span><a href="2-ce.html#SP2" class="function-link"><span class="function-syntax">CopyErrors::new_F</span></a><span class="plain-syntax">(</span><span class="constant-syntax">OPEN_FAILED_CE</span><span class="plain-syntax">, -1, </span><span class="identifier-syntax">F</span><span class="plain-syntax">));</span>
<span class="plain-syntax">            } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">fclose</span><span class="plain-syntax">(</span><span class="identifier-syntax">handle</span><span class="plain-syntax">);</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">succeeded</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">            }</span>
<span class="plain-syntax">        }</span>
<span class="plain-syntax">    }</span>
<span class="plain-syntax">    #</span><span class="identifier-syntax">ifdef</span><span class="plain-syntax"> </span><span class="identifier-syntax">CORE_MODULE</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">succeeded</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">documentation_only</span><span class="plain-syntax"> == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">Main::silence_is_golden</span><span class="plain-syntax">() == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">))</span>
<span class="plain-syntax">        </span><span class="named-paragraph-container code-font"><a href="6-st.html#SP3_2" class="named-paragraph-link"><span class="named-paragraph">Tell console output about the file</span><span class="named-paragraph-number">3.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">    #</span><span class="identifier-syntax">endif</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">currently_lexing_into</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">sf</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP3_1" class="paragraph-anchor"></a><b>&#167;3.1. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Deal with literate source errors</span><span class="named-paragraph-number">3.1</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="identifier-syntax">ls_chapter</span><span class="plain-syntax"> *</span><span class="identifier-syntax">Ch</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">ls_section</span><span class="plain-syntax"> *</span><span class="identifier-syntax">S</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">ls_error</span><span class="plain-syntax"> *</span><span class="identifier-syntax">error</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">Ch</span><span class="plain-syntax">, </span><span class="identifier-syntax">ls_chapter</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">chapters</span><span class="plain-syntax">)</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">S</span><span class="plain-syntax">, </span><span class="identifier-syntax">ls_section</span><span class="plain-syntax">, </span><span class="identifier-syntax">Ch</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">sections</span><span class="plain-syntax">)</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">error</span><span class="plain-syntax">, </span><span class="identifier-syntax">ls_error</span><span class="plain-syntax">, </span><span class="identifier-syntax">S</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">literate_source</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">errors</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">msg</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::new</span><span class="plain-syntax">();</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">WebErrors::write</span><span class="plain-syntax">(</span><span class="identifier-syntax">msg</span><span class="plain-syntax">, </span><span class="identifier-syntax">error</span><span class="plain-syntax">);</span>
<span class="plain-syntax">                </span><a href="2-cps.html#SP5" class="function-link"><span class="function-syntax">Copies::attach_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">, </span><a href="2-ce.html#SP2" class="function-link"><span class="function-syntax">CopyErrors::new_TF</span></a><span class="plain-syntax">(</span><span class="constant-syntax">TANGLE_ERROR_CE</span><span class="plain-syntax">, -1, </span><span class="identifier-syntax">msg</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">));</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">succeeded</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">            }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="6-st.html#SP3">&#167;3</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP3_2" class="paragraph-anchor"></a><b>&#167;3.2. </b>This is where messages like
</p>

<pre class="ConsoleText-displayed-code all-displayed-code code-font">
<span class="ConsoleText-plain-syntax">    I've also read Standard Rules by Graham Nelson, which is 27204 words long.</span>
</pre>
<p class="commentary">are printed to <span class="extract"><span class="ConsoleText-extract-syntax">stdout</span></span> (not <span class="extract"><span class="ConsoleText-extract-syntax">stderr</span></span>), though occasionally I think silence is
golden and that these messages could go. It's a moot point for almost all users,
though, because the console output is concealed from them by the Inform UI
applications.
</p>

<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Tell console output about the file</span><span class="named-paragraph-number">3.2</span></span><span class="ConsoleText-comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">message</span><span class="plain-syntax"> = </span><span class="string-syntax">"I've also read %S, which is %d words long.\n"</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">primary</span><span class="plain-syntax">) </span><span class="identifier-syntax">message</span><span class="plain-syntax"> = </span><span class="string-syntax">"I've now read %S, which is %d words long.\n"</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">wc</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TextFromFiles::total_word_count</span><span class="plain-syntax">(</span><span class="identifier-syntax">sf</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">STDOUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">message</span><span class="plain-syntax">, </span><span class="identifier-syntax">synopsis</span><span class="plain-syntax">, </span><span class="identifier-syntax">wc</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">STREAM_FLUSH</span><span class="plain-syntax">(</span><span class="identifier-syntax">STDOUT</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="identifier-syntax">message</span><span class="plain-syntax">, </span><span class="identifier-syntax">synopsis</span><span class="plain-syntax">, </span><span class="identifier-syntax">wc</span><span class="plain-syntax">);</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="6-st.html#SP3">&#167;3</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>&#167;4. Bridge to the problems system.</b>These are both used when issuing problem messages on content in the relevant
source files.
</p>

<pre class="definitions code-font"><span class="definition-keyword">define</span> <span class="constant-syntax">DESCRIBE_SOURCE_FILE_PROBLEMS_CALLBACK</span><span class="plain-syntax"> </span><a href="6-st.html#SP4" class="function-link"><span class="function-syntax">SourceText::describe_source_file</span></a>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="function-syntax">SourceText::describe_source_file</span><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">paraphrase</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">source_file</span><span class="plain-syntax"> *</span><span class="identifier-syntax">referred</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">file</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">paraphrase</span><span class="plain-syntax"> = </span><span class="identifier-syntax">I</span><span class="string-syntax">"source text"</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">referred</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="5-es.html#SP16" class="function-link"><span class="function-syntax">Extensions::corresponding_to</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">referred</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">matched_filename</span><span class="plain-syntax">)</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">LOOP_OVER</span><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">            </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">F</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">read_into_file</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">Str::clear</span><span class="plain-syntax">(</span><span class="identifier-syntax">matched_filename</span><span class="plain-syntax">);</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">matched_filename</span><span class="plain-syntax">, </span><span class="string-syntax">"%f"</span><span class="plain-syntax">,</span>
<span class="plain-syntax">                    </span><span class="identifier-syntax">TextFromFiles::get_filename</span><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">read_into_file</span><span class="plain-syntax">));</span>
<span class="plain-syntax">                </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::eq</span><span class="plain-syntax">(</span><span class="identifier-syntax">matched_filename</span><span class="plain-syntax">, </span><span class="identifier-syntax">file</span><span class="plain-syntax">)) </span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><span class="identifier-syntax">F</span><span class="plain-syntax">;</span>
<span class="plain-syntax">            }</span>
<span class="plain-syntax">        }</span>
<span class="plain-syntax">    }</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">E</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">inbuild_work</span><span class="plain-syntax"> *</span><span class="identifier-syntax">work</span><span class="plain-syntax"> = </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">edition</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">work</span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">work</span><span class="plain-syntax">) &amp;&amp; (</span><a href="2-wrk.html#SP11" class="function-link"><span class="function-syntax">Works::is_standard_rules</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">work</span><span class="plain-syntax">)))</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">paraphrase</span><span class="plain-syntax"> = </span><span class="identifier-syntax">I</span><span class="string-syntax">"the Standard Rules"</span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">work</span><span class="plain-syntax">) &amp;&amp; (</span><a href="2-wrk.html#SP11" class="function-link"><span class="function-syntax">Works::is_basic_inform</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">work</span><span class="plain-syntax">)))</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">paraphrase</span><span class="plain-syntax"> = </span><span class="identifier-syntax">I</span><span class="string-syntax">"Basic Inform"</span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">else</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">paraphrase</span><span class="plain-syntax"> = </span><span class="identifier-syntax">file</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    }</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">paraphrase</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>&#167;5. </b></p>

<pre class="definitions code-font"><span class="definition-keyword">define</span> <span class="constant-syntax">GLOSS_EXTENSION_SOURCE_FILE_PROBLEMS_CALLBACK</span><span class="plain-syntax"> </span><a href="6-st.html#SP5" class="function-link"><span class="function-syntax">SourceText::gloss_extension</span></a>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">SourceText::gloss_extension</span><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">source_file</span><span class="plain-syntax"> *</span><span class="identifier-syntax">referred</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="5-es.html#SP16" class="function-link"><span class="function-syntax">Extensions::corresponding_to</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">referred</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">E</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">" in the extension %X"</span><span class="plain-syntax">, </span><span class="identifier-syntax">E</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">edition</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">work</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>&#167;6. Bridge to the syntax analyser.</b>Similarly, <a href="index.html" class="internal">supervisor</a> sits on top of the <a href="../syntax-module/index.html" class="internal">syntax</a> module, which forms
up the stream of words from the lexer into syntax trees. This too produces
potential errors, and these will also convert into copy errors, but now we
have a more elegant way to keep track of the copy; <a href="../syntax-module/index.html" class="internal">syntax</a> can be passed
a sort of "your ref" pointer to it.
</p>

<pre class="definitions code-font"><span class="definition-keyword">define</span> <span class="constant-syntax">PROBLEM_REF_SYNTAX_TYPE</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> </span><span class="comment-syntax"> the "your ref" is a pointer to this type</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">PROJECT_REF_SYNTAX_TYPE</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">inform_project</span><span class="plain-syntax"> </span><span class="comment-syntax"> similarly but for the "project ref"</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">PROBLEM_SYNTAX_CALLBACK</span><span class="plain-syntax"> </span><a href="6-st.html#SP6" class="function-link"><span class="function-syntax">SourceText::syntax_problem_handler</span></a>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">SourceText::syntax_problem_handler</span><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">err_no</span><span class="plain-syntax">, </span><span class="identifier-syntax">wording</span><span class="plain-syntax"> </span><span class="identifier-syntax">W</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="constant-syntax">PROBLEM_REF_SYNTAX_TYPE</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">k</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">copy_error</span><span class="plain-syntax"> *</span><span class="identifier-syntax">CE</span><span class="plain-syntax"> = </span><a href="2-ce.html#SP2" class="function-link"><span class="function-syntax">CopyErrors::new_N</span></a><span class="plain-syntax">(</span><span class="constant-syntax">SYNTAX_CE</span><span class="plain-syntax">, </span><span class="identifier-syntax">err_no</span><span class="plain-syntax">, </span><span class="identifier-syntax">k</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><a href="2-ce.html#SP3" class="function-link"><span class="function-syntax">CopyErrors::supply_wording</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">CE</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><a href="2-cps.html#SP5" class="function-link"><span class="function-syntax">Copies::attach_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">, </span><span class="identifier-syntax">CE</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>&#167;7. </b>And in fact we will be producing a number of syntax errors of our own, to
add to those generated in <a href="../syntax-module/index.html" class="internal">syntax</a>.
</p>

<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">ExtMultipleBeginsHere_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">ExtBeginsAfterEndsHere_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">ExtEndsWithoutBegins_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">ExtMultipleEndsHere_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">UseElementWithdrawn_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">UnknownLanguageElement_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">UnknownVirtualMachine_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">HeadingInPlaceOfUnincluded_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">UnequalHeadingInPlaceOf_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">HeadingInPlaceOfSubordinate_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">HeadingInPlaceOfUnknown_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">IncludeExtQuoted_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">BogusExtension_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">ExtVersionTooLow_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">ExtVersionMalformed_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">ExtInadequateVM_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">ExtMisidentifiedEnds_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">UnavailableLOS_SYNERROR</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">DialogueOnSectionsOnly_SYNERROR</span>
</pre>
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>&#167;8. </b>The next tweak to <a href="../syntax-module/index.html" class="internal">syntax</a> is to give it some node metadata. <a href="../syntax-module/index.html" class="internal">syntax</a>
itself places nodes of a small number of basic types into the syntax tree;
we want to expand on those. (And the <a href="../core-module/index.html" class="internal">core</a> module will expand on them still
further, so this still isn't everything: see <a href="../core-module/1-inaa.html" class="internal">Inform-Only Nodes and Annotations (in core)</a>.)
</p>

<p class="commentary">The node types we're adding are for the "structural sentences" which we will
look for below. (The asterisk notation for <span class="extract"><span class="extract-syntax">TRACE_NT</span></span> isn't known to most
Inform users: it increases output to the debugging log.)
</p>

<pre class="definitions code-font"><span class="definition-keyword">define</span> <span class="constant-syntax">NODE_METADATA_SETUP_SYNTAX_CALLBACK</span><span class="plain-syntax"> </span><a href="6-st.html#SP8" class="function-link"><span class="function-syntax">SourceText::node_metadata</span></a>
<span class="definition-keyword">enum</span> <span class="constant-syntax">BIBLIOGRAPHIC_NT</span><span class="plain-syntax">    </span><span class="comment-syntax"> For the initial title sentence</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">IMPERATIVE_NT</span><span class="plain-syntax">       </span><span class="comment-syntax"> "Instead of taking something, ..."</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">INFORM6CODE_NT</span><span class="plain-syntax">      </span><span class="comment-syntax"> "Include (- ... -)</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">TABLE_NT</span><span class="plain-syntax">            </span><span class="comment-syntax"> "Table 1 - Counties of England"</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">EQUATION_NT</span><span class="plain-syntax">         </span><span class="comment-syntax"> "Equation 2 - Newton's Second Law"</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">TRACE_NT</span><span class="plain-syntax">            </span><span class="comment-syntax"> A sentence consisting of an asterisk and optional quoted text</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">list_node_type</span><span class="plain-syntax"> </span><span class="constant-syntax">IMPERATIVE_NT</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">list_entry_node_type</span><span class="plain-syntax"> </span><span class="identifier-syntax">UNKNOWN_NT</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">SourceText::node_metadata</span><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">NodeType::new</span><span class="plain-syntax">(</span><span class="constant-syntax">BIBLIOGRAPHIC_NT</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"BIBLIOGRAPHIC_NT"</span><span class="plain-syntax">,     </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">,     </span><span class="identifier-syntax">L2_NCAT</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">NodeType::new</span><span class="plain-syntax">(</span><span class="constant-syntax">IMPERATIVE_NT</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"IMPERATIVE_NT"</span><span class="plain-syntax">,           </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="identifier-syntax">INFTY</span><span class="plain-syntax">, </span><span class="identifier-syntax">L2_NCAT</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">NodeType::new</span><span class="plain-syntax">(</span><span class="constant-syntax">INFORM6CODE_NT</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"INFORM6CODE_NT"</span><span class="plain-syntax">,         </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">,     </span><span class="identifier-syntax">L2_NCAT</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">NodeType::new</span><span class="plain-syntax">(</span><span class="constant-syntax">TABLE_NT</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"TABLE_NT"</span><span class="plain-syntax">,                     </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">,     </span><span class="identifier-syntax">L2_NCAT</span><span class="plain-syntax">, </span><span class="identifier-syntax">TABBED_NFLAG</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">NodeType::new</span><span class="plain-syntax">(</span><span class="constant-syntax">EQUATION_NT</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"EQUATION_NT"</span><span class="plain-syntax">,               </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">,     </span><span class="identifier-syntax">L2_NCAT</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">NodeType::new</span><span class="plain-syntax">(</span><span class="constant-syntax">TRACE_NT</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"TRACE_NT"</span><span class="plain-syntax">,                     </span><span class="constant-syntax">0</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">,     </span><span class="identifier-syntax">L2_NCAT</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>&#167;9. </b>Sentences in the source text are of five categories: dividing sentences,
which divide up the source into segments; structural sentences, which split
the source into different forms (standard text, tables, equations, I6 matter,
and so on); nonstructural sentences, which make grammatical definitions and
give Inform other more or less direct instructions; rule declarations; and
regular sentences, those which use the standard verbs. Examples:
</p>

<blockquote>
    <p>Volume II [dividing]</p>
</blockquote>

<blockquote>
    <p>Include Locksmith by Emily Short [structural]</p>
</blockquote>

<blockquote>
    <p>Release along with a website [nonstructural]</p>
</blockquote>

<blockquote>
    <p>Instead of looking [rule]</p>
</blockquote>

<blockquote>
    <p>The cushion is on the wooden chair [regular]</p>
</blockquote>

<p class="commentary">Dividing sentences are always read, whereas the others may be skipped in
sections of source not being included for one reason or another.
</p>

<p class="commentary"><a href="../syntax-module/index.html" class="internal">syntax</a> requires us to define the nonterminal <span class="extract"><span class="extract-syntax">&lt;dividing-sentence&gt;</span></span>,
and here goes:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="function-syntax">&lt;dividing-sentence&gt;</span>
<span class="plain-syntax">    </span><span class="function-syntax">&lt;if-start-of-paragraph&gt;</span><span class="plain-syntax"> </span><span class="function-syntax">&lt;heading&gt;</span><span class="plain-syntax"> |</span>
<span class="plain-syntax">    </span><span class="function-syntax">&lt;extension-end-marker-sentence&gt;</span>

<span class="function-syntax">&lt;heading&gt;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">volume</span><span class="plain-syntax"> ... |</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">book</span><span class="plain-syntax"> ... |</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">part</span><span class="plain-syntax"> ... |</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">chapter</span><span class="plain-syntax"> ... |</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">section</span><span class="plain-syntax"> ... ( </span><span class="identifier-syntax">dialog</span><span class="plain-syntax"> ) |</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">section</span><span class="plain-syntax"> ... ( </span><span class="identifier-syntax">dialogue</span><span class="plain-syntax"> ) |</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">section</span><span class="plain-syntax"> ... ( </span><span class="identifier-syntax">dialog</span><span class="plain-syntax"> </span><span class="identifier-syntax">during</span><span class="plain-syntax"> ... ) |</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">section</span><span class="plain-syntax"> ... ( </span><span class="identifier-syntax">dialogue</span><span class="plain-syntax"> </span><span class="identifier-syntax">during</span><span class="plain-syntax"> ... ) |</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">section</span><span class="plain-syntax"> ...</span>

<span class="function-syntax">&lt;extension-end-marker-sentence&gt;</span>
<span class="plain-syntax">    ... </span><span class="identifier-syntax">begin</span><span class="plain-syntax">/</span><span class="identifier-syntax">begins</span><span class="plain-syntax"> </span><span class="identifier-syntax">here</span><span class="plain-syntax"> |</span>
<span class="plain-syntax">    ... </span><span class="identifier-syntax">end</span><span class="plain-syntax">/</span><span class="identifier-syntax">ends</span><span class="plain-syntax"> </span><span class="identifier-syntax">here</span>
</pre>
<p class="commentary firstcommentary"><a id="SP9_1" class="paragraph-anchor"></a><b>&#167;9.1. </b>Note that the extension end markers are only read in extensions, so they can
never accidentally match in the main source text.
</p>

<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Check we can begin an extension here</span><span class="named-paragraph-number">9.1</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">switch</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sfsm</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">ext_pos</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span><span class="plain-syntax">: </span><span class="identifier-syntax">sfsm</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">ext_pos</span><span class="plain-syntax">++; </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span><span class="plain-syntax">: </span><span class="constant-syntax">PROBLEM_SYNTAX_CALLBACK</span><span class="plain-syntax">(</span><span class="constant-syntax">ExtMultipleBeginsHere_SYNERROR</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">sfsm</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">ref</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="constant-syntax">3</span><span class="plain-syntax">: </span><span class="constant-syntax">PROBLEM_SYNTAX_CALLBACK</span><span class="plain-syntax">(</span><span class="constant-syntax">ExtBeginsAfterEndsHere_SYNERROR</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">sfsm</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">ref</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="6-st.html#SP9">&#167;9</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP9_2" class="paragraph-anchor"></a><b>&#167;9.2. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Check we can end an extension here</span><span class="named-paragraph-number">9.2</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">switch</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sfsm</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">ext_pos</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span><span class="plain-syntax">: </span><span class="constant-syntax">PROBLEM_SYNTAX_CALLBACK</span><span class="plain-syntax">(</span><span class="constant-syntax">ExtEndsWithoutBegins_SYNERROR</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">sfsm</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">ref</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span><span class="plain-syntax">: </span><span class="identifier-syntax">sfsm</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">ext_pos</span><span class="plain-syntax">++; </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="constant-syntax">3</span><span class="plain-syntax">: </span><span class="constant-syntax">PROBLEM_SYNTAX_CALLBACK</span><span class="plain-syntax">(</span><span class="constant-syntax">ExtMultipleEndsHere_SYNERROR</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">sfsm</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">ref</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="6-st.html#SP9">&#167;9</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP10" class="paragraph-anchor"></a><b>&#167;10. </b><a href="../syntax-module/index.html" class="internal">syntax</a> also requires this definition:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="function-syntax">&lt;structural-sentence&gt;</span>
<span class="plain-syntax">    </span><span class="function-syntax">&lt;if-start-of-source-text&gt;</span><span class="plain-syntax"> </span><span class="function-syntax">&lt;quoted-text&gt;</span><span class="plain-syntax"> |</span>
<span class="plain-syntax">    </span><span class="function-syntax">&lt;if-start-of-source-text&gt;</span><span class="plain-syntax"> </span><span class="function-syntax">&lt;quoted-text&gt;</span><span class="plain-syntax"> ... |</span>
<span class="plain-syntax">    </span><span class="function-syntax">&lt;language-modifying-sentence&gt;</span><span class="plain-syntax"> |</span>
<span class="plain-syntax">    * |</span>
<span class="plain-syntax">    * </span><span class="function-syntax">&lt;quoted-text-without-subs&gt;</span><span class="plain-syntax"> |</span>
<span class="plain-syntax">    </span><span class="function-syntax">&lt;if-start-of-paragraph&gt;</span><span class="plain-syntax"> </span><span class="identifier-syntax">table</span><span class="plain-syntax"> ... |</span>
<span class="plain-syntax">    </span><span class="function-syntax">&lt;if-start-of-paragraph&gt;</span><span class="plain-syntax"> </span><span class="identifier-syntax">equation</span><span class="plain-syntax"> ... |</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">include</span><span class="plain-syntax"> </span><span class="identifier-syntax">the</span><span class="plain-syntax"> ... </span><span class="identifier-syntax">by</span><span class="plain-syntax"> ... |</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">include</span><span class="plain-syntax"> ... </span><span class="identifier-syntax">by</span><span class="plain-syntax"> ... |</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">include</span><span class="plain-syntax"> (- ...</span>
</pre>
<p class="commentary firstcommentary"><a id="SP11" class="paragraph-anchor"></a><b>&#167;11. </b>Rules are ordinarily detected by their colon, which divides the header from the
rest: colons are not otherwise legal in Inform. But there's an exception. If the
sentence consists of text matching the following grammar, followed by comma,
followed by more text, then the comma is read as if it's a colon and the
sentence becomes a rule. For example:
</p>

<blockquote>
    <p>Instead of going north, try entering the cage</p>
</blockquote>

<pre class="displayed-code all-displayed-code code-font">
<span class="function-syntax">&lt;comma-divisible-sentence&gt;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">instead</span><span class="plain-syntax"> </span><span class="identifier-syntax">of</span><span class="plain-syntax"> ... |</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">every</span><span class="plain-syntax"> </span><span class="identifier-syntax">turn</span><span class="plain-syntax"> *** |</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">before</span><span class="plain-syntax"> ... |</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">after</span><span class="plain-syntax"> ... |</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">when</span><span class="plain-syntax"> ...</span>
</pre>
<p class="commentary firstcommentary"><a id="SP12" class="paragraph-anchor"></a><b>&#167;12. </b>Properly speaking, despite the definition above, language modifying sentences
are nonstructural. So what are they doing here? The answer is that we need to
read them early on, because they affect the way that they parse all other
sentences. Whereas other nonstructural sentences can wait, these can't.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="function-syntax">&lt;language-modifying-sentence&gt;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">include</span><span class="plain-syntax"> (- ### </span><span class="identifier-syntax">in</span><span class="plain-syntax"> </span><span class="identifier-syntax">the</span><span class="plain-syntax"> </span><span class="identifier-syntax">preform</span><span class="plain-syntax"> </span><span class="identifier-syntax">grammar</span><span class="plain-syntax"> |</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">use</span><span class="plain-syntax"> ... </span><span class="identifier-syntax">language</span><span class="plain-syntax"> </span><span class="identifier-syntax">element</span><span class="plain-syntax">/</span><span class="identifier-syntax">elements</span>
</pre>
<p class="commentary firstcommentary"><a id="SP13" class="paragraph-anchor"></a><b>&#167;13. </b>The following callback function is called by <a href="../syntax-module/index.html" class="internal">syntax</a> when it breaks a
sentence of type <span class="extract"><span class="extract-syntax">BEGINHERE_NT</span></span> or <span class="extract"><span class="extract-syntax">ENDHERE_NT</span></span> &mdash; i.e., the beginning or end
of an extension.
</p>

<pre class="definitions code-font"><span class="definition-keyword">define</span> <span class="constant-syntax">BEGIN_OR_END_HERE_SYNTAX_CALLBACK</span><span class="plain-syntax"> </span><a href="6-st.html#SP13" class="function-link"><span class="function-syntax">SourceText::new_beginend</span></a>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">SourceText::new_beginend</span><span class="plain-syntax">(</span><span class="identifier-syntax">parse_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pn</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inform_extension</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="5-es.html#SP6" class="function-link"><span class="function-syntax">Extensions::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Node::get_type</span><span class="plain-syntax">(</span><span class="identifier-syntax">pn</span><span class="plain-syntax">) == </span><span class="identifier-syntax">BEGINHERE_NT</span><span class="plain-syntax">) </span><a href="6-inc.html#SP10" class="function-link"><span class="function-syntax">Inclusions::check_begins_here</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pn</span><span class="plain-syntax">, </span><span class="identifier-syntax">E</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Node::get_type</span><span class="plain-syntax">(</span><span class="identifier-syntax">pn</span><span class="plain-syntax">) == </span><span class="identifier-syntax">ENDHERE_NT</span><span class="plain-syntax">) </span><a href="6-inc.html#SP11" class="function-link"><span class="function-syntax">Inclusions::check_ends_here</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pn</span><span class="plain-syntax">, </span><span class="identifier-syntax">E</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP14" class="paragraph-anchor"></a><b>&#167;14. </b>This callback is called by <a href="../syntax-module/index.html" class="internal">syntax</a> when it first reaches a dialogue line
or beat.
</p>

<pre class="definitions code-font"><span class="definition-keyword">define</span> <span class="constant-syntax">DIALOGUE_WARNING_SYNTAX_CALLBACK</span><span class="plain-syntax"> </span><a href="5-ps2.html#SP33" class="function-link"><span class="function-syntax">Projects::dialogue_present</span></a>
</pre>
<p class="commentary firstcommentary"><a id="SP15" class="paragraph-anchor"></a><b>&#167;15. </b>Lastly, this callback is called by <a href="../syntax-module/index.html" class="internal">syntax</a> when it hits a sentence like:
</p>

<blockquote>
    <p>Use interactive fiction language element.</p>
</blockquote>

<p class="commentary">This feature of Inform has been withdrawn (it has moved lower down the software
stack into the new world of kits), so we issue a syntax error.
</p>

<pre class="definitions code-font"><span class="definition-keyword">define</span> <span class="constant-syntax">LANGUAGE_ELEMENT_SYNTAX_CALLBACK</span><span class="plain-syntax"> </span><a href="6-st.html#SP15" class="function-link"><span class="function-syntax">SourceText::new_language</span></a>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">SourceText::new_language</span><span class="plain-syntax">(</span><span class="identifier-syntax">wording</span><span class="plain-syntax"> </span><span class="identifier-syntax">W</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">copy_error</span><span class="plain-syntax"> *</span><span class="identifier-syntax">CE</span><span class="plain-syntax"> = </span><a href="2-ce.html#SP2" class="function-link"><span class="function-syntax">CopyErrors::new</span></a><span class="plain-syntax">(</span><span class="constant-syntax">SYNTAX_CE</span><span class="plain-syntax">, </span><span class="constant-syntax">UseElementWithdrawn_SYNERROR</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><a href="2-ce.html#SP3" class="function-link"><span class="function-syntax">CopyErrors::supply_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">CE</span><span class="plain-syntax">, </span><span class="identifier-syntax">current_sentence</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><a href="2-cps.html#SP5" class="function-link"><span class="function-syntax">Copies::attach_error</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">sfsm</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">ref</span><span class="plain-syntax">, </span><span class="identifier-syntax">CE</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<nav role="progress"><div class="progresscontainer">
    <ul class="progressbar"><li class="progressprev"><a href="5-ts.html">&#10094;</a></li><li class="progresschapter"><a href="P-wtmd.html">P</a></li><li class="progresschapter"><a href="1-sm.html">1</a></li><li class="progresschapter"><a href="2-gnr.html">2</a></li><li class="progresschapter"><a href="3-bg.html">3</a></li><li class="progresschapter"><a href="4-em.html">4</a></li><li class="progresschapter"><a href="5-es.html">5</a></li><li class="progresscurrentchapter">6</li><li class="progresscurrent">st</li><li class="progresssection"><a href="6-hdn.html">hdn</a></li><li class="progresssection"><a href="6-tof.html">tof</a></li><li class="progresssection"><a href="6-inc.html">inc</a></li><li class="progresssection"><a href="6-cs.html">cs</a></li><li class="progresssection"><a href="6-vmg.html">vmg</a></li><li class="progresschapter"><a href="7-tm.html">7</a></li><li class="progressnext"><a href="6-hdn.html">&#10095;</a></li></ul></div>
</nav><!-- End of weave -->

		</main>
	</body>
</html>

